home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_HDF.idb / usr / freeware / include / hdf / atom.h.z / atom.h
Encoding:
C/C++ Source or Header  |  1999-01-26  |  11.3 KB  |  301 lines
  1. /****************************************************************************
  2.  * NCSA HDF                                                                 *
  3.  * Software Development Group                                               *
  4.  * National Center for Supercomputing Applications                          *
  5.  * University of Illinois at Urbana-Champaign                               *
  6.  * 605 E. Springfield, Champaign IL 61820                                   *
  7.  *                                                                          *
  8.  * For conditions of distribution and use, see the accompanying             *
  9.  * hdf/COPYING file.                                                        *
  10.  *                                                                          *
  11.  ****************************************************************************/
  12.  
  13. /* $Id: atom.h,v 1.7 1997/11/13 14:50:41 koziol Exp $ */
  14.  
  15. /*-----------------------------------------------------------------------------
  16.  * File:    atom.h
  17.  * Purpose: header file for atom API
  18.  * Dependencies: 
  19.  * Invokes:
  20.  * Contents:
  21.  * Structure definitions: 
  22.  * Constant definitions: 
  23.  *---------------------------------------------------------------------------*/
  24.  
  25. /* avoid re-inclusion */
  26. #ifndef __ATOM_H
  27. #define __ATOM_H
  28.  
  29. /* Atom Features control */
  30. /* Define the following macro for fast hash calculations (but limited hash sizes) */
  31. #define HASH_SIZE_POWER_2
  32.  
  33. /* Define the following macro for atom caching over all the atoms */
  34. #define ATOMS_ARE_CACHED
  35.  
  36. /* Define the following macro for "inline" atom lookups from the cache */
  37. #ifdef ATOMS_ARE_CACHED     /* required for this to work */
  38. #define ATOMS_CACHE_INLINE
  39. #endif /* ATOMS_ARE_CACHED */
  40.  
  41. #ifdef ATOMS_CACHE_INLINE
  42. /* Do swap using XOR operator. Ugly but fast... -QAK */
  43. #define HAIswap_cache(i,j) \
  44.                 atom_id_cache[i]^=atom_id_cache[j], \
  45.                 atom_obj_cache[i]=(void *)((hdf_pint_t)atom_obj_cache[j]^(hdf_pint_t)atom_obj_cache[i]), \
  46.                 atom_id_cache[j]^=atom_id_cache[i], \
  47.                 atom_obj_cache[j]=(void *)((hdf_pint_t)atom_obj_cache[i]^(hdf_pint_t)atom_obj_cache[j]), \
  48.                 atom_id_cache[i]^=atom_id_cache[j], \
  49.                 atom_obj_cache[i]=(void *)((hdf_pint_t)atom_obj_cache[i]^(hdf_pint_t)atom_obj_cache[j])
  50.  
  51. /* Note! This is hardwired to the atom cache value being 4 */
  52. #define HAatom_object(atm) \
  53.     (atom_id_cache[0]==atm ? atom_obj_cache[0] : \
  54.       atom_id_cache[1]==atm ? (HAIswap_cache(0,1),atom_obj_cache[0]) : \
  55.        atom_id_cache[2]==atm ? (HAIswap_cache(1,2),atom_obj_cache[1]) : \
  56.         atom_id_cache[3]==atm ? (HAIswap_cache(2,3),atom_obj_cache[2]) : \
  57.          HAPatom_object(atm))
  58. #endif /* ATOMS_CACHE_INLINE */
  59.  
  60. #include "hdf.h"
  61.  
  62. /* Group values allowed */
  63. typedef enum {BADGROUP=(-1),    /* Invalid Group */
  64. DDGROUP=0,                  /* Group ID for DD objects */
  65. AIDGROUP=1,                 /* Group ID for access ID objects */
  66. FIDGROUP=2,                 /* Group ID for file ID objects */
  67. VGIDGROUP=3,                /* Group ID for Vgroup ID objects */
  68. VSIDGROUP=4,                /* Group ID for Vdata ID objects */
  69. GRIDGROUP=5,                /* Group ID for GR ID objects */
  70. RIIDGROUP=6,                /* Group ID for RI ID objects */
  71. BITIDGROUP=7,               /* Group ID for Bitfile ID objects */
  72. ANIDGROUP=8,                /* Group ID for Annotation ID objects */
  73. MAXGROUP                    /* Highest group in group_t (Invalid as true group) */
  74. } group_t;
  75.  
  76. /* Type of atoms to return to users */
  77. typedef int32 atom_t;
  78.  
  79. /* Type of the function to compare objects & keys */
  80. typedef intn (*HAsearch_func_t)(const void * obj, const void * key);
  81.  
  82. #if defined ATOM_MASTER | defined ATOM_TESTER
  83.  
  84. /* # of bits to use for Group ID in each atom (change if MAXGROUP>16) */
  85. #define GROUP_BITS  4
  86. #define GROUP_MASK  0x0F
  87.  
  88. /* # of bits to use for the Atom index in each atom (change if MAXGROUP>16) */
  89. #define ATOM_BITS   28
  90. #define ATOM_MASK   0x0FFFFFFF
  91.  
  92. #ifdef ATOMS_ARE_CACHED
  93. /* # of previous atoms cached, change inline caching macros (HAatom_object & HAIswap_cache) if this changes */
  94. #define ATOM_CACHE_SIZE 4
  95. #endif /* ATOMS_ARE_CACHED */
  96.  
  97. /* Map an atom to a Group number */
  98. #define ATOM_TO_GROUP(a)    ((group_t)((((atom_t)(a))>>((sizeof(atom_t)*8)-GROUP_BITS))&GROUP_MASK))
  99.  
  100. #ifdef HASH_SIZE_POWER_2
  101. /* Map an atom to a hash location (assumes s is a power of 2 and smaller than the ATOM_MASK constant) */
  102. #define ATOM_TO_LOC(a,s)    ((atom_t)(a)&((s)-1))
  103. #else /* HASH_SIZE_POWER_2 */
  104. /* Map an atom to a hash location */
  105. #define ATOM_TO_LOC(a,s)    (((atom_t)(a)&ATOM_MASK)%(s))
  106. #endif /* HASH_SIZE_POWER_2 */
  107.  
  108. /* Combine a Group number and an atom index into an atom */
  109. #define MAKE_ATOM(g,i)      ((((atom_t)(g)&GROUP_MASK)<<((sizeof(atom_t)*8)-GROUP_BITS))|((atom_t)(i)&ATOM_MASK))
  110.  
  111. /* Atom information structure used */
  112. typedef struct atom_info_struct_tag {
  113.     atom_t id;              /* atom ID for this info */
  114.     VOIDP *obj_ptr;         /* pointer associated with the atom */
  115.     struct atom_info_struct_tag *next;   /* link to next atom (in case of hash-clash) */
  116.   }atom_info_t;
  117.  
  118. /* Atom group structure used */
  119. typedef struct atom_group_struct_tag {
  120.     uintn count;            /* # of times this group has been initialized */
  121.     intn hash_size;         /* size of the hash table to store the atoms in */
  122.     uintn atoms;            /* current number of atoms held */
  123.     uintn nextid;           /* atom ID to use for the next atom */
  124.     atom_info_t **atom_list;/* pointer to an array of ptrs to atoms */
  125.   }atom_group_t;
  126.  
  127. /* Define this in only one place */
  128. #ifdef ATOM_MASTER
  129.  
  130. /* Array of pointers to atomic groups */
  131. static atom_group_t *atom_group_list[MAXGROUP]={NULL};
  132.  
  133. /* Pointer to the atom node free list */
  134. static atom_info_t *atom_free_list=NULL;
  135.  
  136. #ifdef ATOMS_ARE_CACHED
  137. /* Array of pointers to atomic groups */
  138. #ifdef OLD_WAY
  139. static atom_t atom_id_cache[ATOM_CACHE_SIZE]={-1,-1,-1,-1};
  140. static VOIDP atom_obj_cache[ATOM_CACHE_SIZE]={NULL};
  141. #else /* OLD_WAY */
  142. atom_t atom_id_cache[ATOM_CACHE_SIZE]={-1,-1,-1,-1};
  143. VOIDP atom_obj_cache[ATOM_CACHE_SIZE]={NULL};
  144. #endif /* OLD_WAY */
  145. #endif /* ATOMS_ARE_CACHED */
  146. #endif /* ATOM_MASTER */
  147.  
  148. /* Useful routines for generally private use */
  149.  
  150. #endif /* ATOM_MASTER | ATOM_TESTER */
  151.  
  152. #ifndef ATOM_MASTER
  153. extern atom_t atom_id_cache[];
  154. extern VOIDP atom_obj_cache[];
  155. #endif /* ATOM_MASTER */
  156.  
  157. #if defined c_plusplus || defined __cplusplus
  158. extern      "C"
  159. {
  160. #endif                          /* c_plusplus || __cplusplus */
  161.  
  162. /******************************************************************************
  163.  NAME
  164.      HAinit_group - Initialize an atomic group
  165.  
  166.  DESCRIPTION
  167.     Creates an atomic group to store atoms in.  If the group has already been
  168.     initialized, this routine just increments the count of # of initializations
  169.     and returns without trying to change the size of the hash table.
  170.  
  171.  RETURNS
  172.     Returns SUCCEED if successful and FAIL otherwise
  173.  
  174. *******************************************************************************/
  175. intn HAinit_group(group_t grp,      /* IN: Group to initialize */
  176.     intn hash_size                  /* IN: Minimum hash table size to use for group */
  177. );
  178.  
  179. /******************************************************************************
  180.  NAME
  181.      HAdestroy_group - Destroy an atomic group
  182.  
  183.  DESCRIPTION
  184.     Destroys an atomic group which atoms are stored in.  If the group still
  185.     has atoms which are registered, this routine fails.  If there have been
  186.     multiple initializations of the group, this routine just decrements the
  187.     count of initializations and does not check the atoms out-standing.
  188.  
  189.  RETURNS
  190.     Returns SUCCEED if successful and FAIL otherwise
  191.  
  192. *******************************************************************************/
  193. intn HAdestroy_group(group_t grp       /* IN: Group to destroy */
  194. );
  195.  
  196. /******************************************************************************
  197.  NAME
  198.      HAregister_atom - Register an object in a group and get an atom for it.
  199.  
  200.  DESCRIPTION
  201.     Registers an object in a group and returns an atom for it.  This routine
  202.     does _not_ check for unique-ness of the objects, if you register an object
  203.     twice, you will get two different atoms for it.  This routine does make
  204.     certain that each atom in a group is unique.  Atoms are created by getting
  205.     a unique number for the group the atom is in and incorporating the group
  206.     into the atom which is returned to the user.
  207.  
  208.  RETURNS
  209.     Returns atom if successful and FAIL otherwise
  210.  
  211. *******************************************************************************/
  212. atom_t HAregister_atom(group_t grp,     /* IN: Group to register the object in */
  213.     VOIDP object                        /* IN: Object to attach to atom */
  214. );
  215.  
  216. /******************************************************************************
  217.  NAME
  218.      HAatom_object - Returns to the object ptr for the atom 
  219.  
  220.  DESCRIPTION
  221.     Retrieves the object ptr which is associated with the atom.
  222.  
  223.  RETURNS
  224.     Returns object ptr if successful and NULL otherwise
  225.  
  226. *******************************************************************************/
  227. #ifdef ATOMS_CACHE_INLINE
  228. VOIDP HAPatom_object(atom_t atm   /* IN: Atom to retrieve object for */
  229. );
  230. #else /* ATOMS_CACHE_INLINE */
  231. VOIDP HAatom_object(atom_t atm   /* IN: Atom to retrieve object for */
  232. );
  233. #endif /* ATOMS_CACHE_INLINE */
  234.  
  235. /******************************************************************************
  236.  NAME
  237.      HAatom_group - Returns to the group for the atom 
  238.  
  239.  DESCRIPTION
  240.     Retrieves the group which is associated with the atom.
  241.  
  242.  RETURNS
  243.     Returns group if successful and FAIL otherwise
  244.  
  245. *******************************************************************************/
  246. group_t HAatom_group(atom_t atm   /* IN: Atom to retrieve group for */
  247. );
  248.  
  249. /******************************************************************************
  250.  NAME
  251.      HAremove_atom - Removes an atom from a group
  252.  
  253.  DESCRIPTION
  254.     Removes an atom from a group.
  255.  
  256.  RETURNS
  257.     Returns atom's object if successful and FAIL otherwise
  258.  
  259. *******************************************************************************/
  260. VOIDP HAremove_atom(atom_t atm   /* IN: Atom to remove */
  261. );
  262.  
  263. /******************************************************************************
  264.  NAME
  265.      HAsearch_atom - Search for an object in a group and get it's pointer.
  266.  
  267.  DESCRIPTION
  268.     Searchs for an object in a group and returns the pointer to it.
  269.     This routine calls the function pointer passed in for each object in the
  270.     group until it finds a match.  Currently there is no way to resume a
  271.     search.
  272.  
  273.  RETURNS
  274.     Returns pointer an atom's object if successful and NULL otherwise
  275.  
  276. *******************************************************************************/
  277. VOIDP HAsearch_atom(group_t grp,        /* IN: Group to search for the object in */
  278.     HAsearch_func_t func,               /* IN: Ptr to the comparison function */
  279.     const void * key                     /* IN: pointer to key to compare against */
  280. );
  281.  
  282. /******************************************************************************
  283.  NAME
  284.      HAshutdown - Terminate various static buffers.
  285.  
  286.  DESCRIPTION
  287.     Free various buffers allocated in the HA routines.
  288.  
  289.  RETURNS
  290.     Returns SUCCEED/FAIL
  291.  
  292. *******************************************************************************/
  293. intn HAshutdown(void);
  294.  
  295. #if defined c_plusplus || defined __cplusplus
  296. }
  297. #endif                          /* c_plusplus || __cplusplus */
  298.  
  299. #endif /* __ATOM_H */
  300.  
  301.